Skip to content

fix(doctor): tell an empty or no-Studio-Pro Windows/macOS machine the truth - #775

Merged
MendixMau merged 4 commits into
masterfrom
fix/empty-folder-bootstrap
Nov 16, 2026
Merged

MendixMau merged 4 commits into
masterfrom
fix/empty-folder-bootstrap

Conversation

@MendixMau

Copy link
Copy Markdown
Owner

Direct lane

What changed and why (one paragraph):
A customer's Windows 11 / Git Bash setup (empty folder under OneDrive, no Studio Pro, no Docker, a non-Claude agent) hit four doctor FAILs from the missing .mpr, then followed doctor's advice ("No Studio Pro needed for the gate: --install downloads the standalone toolchain") into mxcli new, which left a 373 MB partial Linux mxbuild and no app. Off Linux that advice is wrong: the Mendix CDN publishes Linux mxbuild only (mxcli NativeMxBuildForSetup, #916), and mxcli setup mxbuild refuses there. Doctor now (1) on macOS/Git Bash skips the ~800 MB plan and the dead setup mxbuild call, and says install Studio Pro in the app's version or use the Dev Container; (2) with no .mpr, says there is no app yet and how to create one (Studio Pro New app > Blank outside OneDrive, or mxcli new before mxcli init); (3) no longer names mxcli init as the source of a new .mpr; (4) reports the Claude Code permissions section as "skipped" when Claude Code is not on the machine (MXTK_CLAUDE=1 forces it). README's no-Studio-Pro note now says Linux only. Three upstream drafts added to bug-logs/pending-github-issues/ (not filed).

Impact

Row Answer
Process No new steps or gates. Doctor output only: a dead download is replaced by a FAIL with the real remedy. Nothing new blocks.
Dependencies bin/doctor.sh only (no _common.sh/exec.sh change). Uses existing mxtk_model_version. New env MXTK_CLAUDE (optional). No order dependency on open PRs.
Context cost none: no routed or always-loaded file touched (README section is not in baseline routing).
Behaviour n/a: scripts and README only.
Runtime Saves an ~800 MB download that cannot run, on macOS/Windows without Studio Pro. New fixture: ~90 s on an M-series Mac. Time cost: per CI run · ~90 s on macOS arm64 · can force rework: n · offset: maintainer OK.

Field evidence: observed on a customer's Windows 11 / Git Bash machine (described above, from the customer's setup report). The changed doctor has not yet run on a real Windows machine; Windows and macOS are simulated with a fake uname + MXTK_PLATFORM and a call-logging stub mxcli. A supervised re-run on that machine is planned.

Tests

  • tests/wave2/test-doctor-no-app-no-sp.sh: 21/21. On the previous doctor 10 of its checks fail (the stub shows setup mxbuild called on Windows and macOS). Covers: Windows empty folder, Windows/macOS app without Studio Pro, Linux unchanged, macOS and Windows WITH Studio Pro unchanged, no-Claude section skipped.

  • Existing: test-doctor-mxcli-arch 10/10, test-doctor-portable 24/24, test-doctor-mxcli-latest 12/12, test-doctor-stale-hooks 7/7.

  • check-scripts 137/137, check-portability clean, leak guard clean, check-pr-discipline clean.

  • Local run-all.sh was stopped at its 1-hour limit (102 of 223 fixtures run). Every failure it showed was compared on an untouched origin/master worktree, with the same count on both: app-readiness, app-restart, baseline-loosen-lock, common-root-multiapp, common-windows, company-brain, doctor-bench, doctor-gate-selftest, file-bugs (local macOS environment). bug12-sync fails on both with varying counts (flaky locally); it tests sync-project.sh, untouched here. T3 left to CI.

  • No client data anywhere in the diff

  • Size cap: 7 files; ~190 lines excluding CHANGELOG and drafts

  • Test tier reached: T1 (new fixture + related doctor fixtures); T2 pending (real Windows re-run)

  • Both platforms considered (macOS, Git Bash, Linux, WSL keeps the Linux path); both layouts (toolchain_skip_reason checks root and app/)

  • CHANGELOG.md line appended, credited

  • No new bug numbers

🤖 Generated with Claude Code

MendixMau and others added 2 commits November 16, 2026 10:01
… truth

The Mendix CDN publishes Linux mxbuild only, so off Linux `doctor.sh --install`
cannot download a gate that runs. Doctor said otherwise, and its project
help text named `mxcli init` as the source of a new .mpr (init creates no app).

- --install on macOS/Git Bash: no ~800 MB plan, no `mxcli setup mxbuild` call;
  says install Studio Pro in the app's version or use the Dev Container.
- --install with no .mpr: says there is no app yet and how to make one
  (Studio Pro New app > Blank outside OneDrive, or `mxcli new` before `init`).
- Claude Code permissions section: "skipped" when Claude Code is not on the
  machine (MXTK_CLAUDE=1 forces it), instead of two WARNs a non-Claude agent
  cannot act on.
- README no-Studio-Pro note: Linux only; empty-folder order.
- tests/wave2/test-doctor-no-app-no-sp.sh: 15/15 (10 fail on the old doctor).
- Three upstream drafts in bug-logs/pending-github-issues/.

Field: a customer's Windows 11 / Git Bash setup, empty OneDrive folder,
no Studio Pro, no Docker, non-Claude agent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…m pinned for the fake OS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MendixMau

Copy link
Copy Markdown
Owner Author

Review: MERGE-AFTER-FIX. CI checks is red because of this PR. The new no-Claude skip (bin/doctor.sh:2093) silences the hook checks that test-look-ledger-hook-repair.sh (H2, H4) and test-look-hook-cwd.sh (L9) assert. This happens on any host without claude or ~/.claude.

Value: Fixes the reported dead end.

  • Off Linux, --install no longer plans the ~800 MB download or calls setup mxbuild (bin/doctor.sh:1426-1450, 1487-1495).
  • An empty folder gets "no app yet" plus the order new before init (2053-2055, README:326-337).
  • The "Linux only" claim matches upstream: mxcli cmd/mxcli/docker/mxbuild_platform.go says the CDN publishes Linux archives only, and MxBuildCDNURL branches on GOARCH, never on GOOS.
  • Nothing is overbuilt.
  • The three upstream drafts are well scoped and hold no client data: <user> path, no customer name.

Regression risk:

  • (a) Hook fixtures break. On a CI runner, or in a container or a non-Claude agent session with no ~/.claude, the permissions and hook section now prints "skipped". That is intended for humans, but it breaks two existing fixtures. The base commit (6dad68f) is green and the head (a46da88) fails H2/H4/L9. Reproduced locally with an empty HOME and no claude on PATH; with the real HOME, both fixtures pass.
  • (b) WSL gets the wrong text. The else branch at 1661-1662 now says "On wsl the gate needs Studio Pro's own mxbuild … cannot download one that runs here". That is false: WSL is Linux, and toolchain_skip_reason (1431) and 1697 both treat it as Linux.
  • (c) Contradicting skill text. skills/doctor-triage.md:100 still says the cache lane works on macOS when the build is Mach-O (Local lane: no single 'what runs where' answer (MxBuild/runtime/DB/Playwright, Docker or not); doctor-triage says the ~/.mxcli/mxbuild cache is Linux-only but it holds a working Mach-O arm64 build on macOS #525). That line now contradicts doctor. Not a blocker.
  • (d) Layouts. The skip checks both *.mpr and app/*.mpr. install_toolchain (1454) is still root-only, as before.
  • (e) Syntax, exit codes, conflicts. No bash 4 syntax. No new exit codes or refusals; the only verdict change is that the old dead download becomes a FAIL. No conflict with origin/master.

Correctness:

  • Fixtures run in a detached worktree, all passing:
    • the new fixture: 21/21
    • doctor-mxcli-arch: 10/10
    • doctor-portable: all passed
    • doctor-mxcli-latest: 12/12
    • doctor-stale-hooks: 7/7
  • The OS is simulated (fake uname plus MXTK_PLATFORM). The changed doctor has not had a Windows field run yet.

Context cost: 66196 → 66196 words (measured on both).

Time cost: nothing per build row. CI adds about 22 s for the new fixture.

Exact fixes required:

  1. Set MXTK_CLAUDE=1 on the doctor.sh invocations in tests/wave2/test-look-ledger-hook-repair.sh (H2/H4) and tests/wave2/test-look-hook-cwd.sh (L7/L9), or create $HOME/.claude under a fake HOME there. Then get CI checks green.
  2. bin/doctor.sh:1661: make WSL take the Linux text, either by matching linux|wsl or by limiting the new lines to macos/gitbash.
  3. (Recommended) Update the cache-lane row at skills/doctor-triage.md:100: CDN downloads are Linux-only, and a Mach-O cache comes from Studio Pro.

Generated by Claude Code

…Linux text; doctor-triage cache lane is Linux-only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSjXefSNicGGqP4aiSC
@MendixMau

Copy link
Copy Markdown
Owner Author

Review fixes pushed in f891bc8, at the maintainer's request:

  1. The doctor.sh calls in test-look-ledger-hook-repair.sh (H2/H4) and test-look-hook-cwd.sh (L9) now set MXTK_CLAUDE=1. That turns their hook checks back on when the runner has no Claude Code installed.
  2. bin/doctor.sh:1651: WSL now gets the Linux text, matching :1697.
  3. skills/doctor-triage.md:100: the cache-lane row now says Linux only (WSL included). A Mach-O build found in the cache is treated as the Studio Pro lane.

I did not re-run the fixtures locally. CI checks on f891bc8 is the proof. A re-review follows once it is green.


Generated by Claude Code

@MendixMau

Copy link
Copy Markdown
Owner Author

Review: MERGE (re-review). All three fixes from the first review are in and correct (f891bc8). The master merge (9a1feb3) only joins the two CHANGELOG sides. CI checks and authoring-audit on 9a1feb3 both completed with success.

Value: The PR fixes the reported dead end. Off Linux it no longer plans a download that cannot work, and an empty folder now gets "no app yet" with the new-before-init order. Fix 2 landed: bin/doctor.sh:1651 is now linux || wsl, which matches :1697 and :1894/1908.

Regression risk:

  • Fix 1 landed. test-look-ledger-hook-repair.sh:58,109,127 (H2, H8, H4) and test-look-hook-cwd.sh:125 (L9) set MXTK_CLAUDE=1. L7 is a grep over doctor.sh and never runs it, so it needed no change.
  • Control run, with HOME empty and no claude on PATH: the pre-fix fixtures fail (hook-repair 11/2, hook-cwd 8/1), and the fixed ones pass (13/0, 9/0).
  • Master merge. git show --remerge-diff 9a1feb38 shows only the CHANGELOG markers removed, with both sides kept. No conflict with origin/master.

Correctness: Run in a detached worktree at 9a1feb3. The two hook fixtures and stale-hooks also pass with no claude and an empty HOME.

Fixture Pass / fail
no-app-no-sp 21/0
mxcli-arch 10/0
portable 24/0
mxcli-latest 12/0
stale-hooks 7/0
gate-selftest 42/0
docker-probe 18/0
bench 72/0
gitignore-crlf 33/0
look-hook-cwd 9/0
look-ledger-hook-repair 13/0

Nit, not blocking: skills/doctor-triage.md:100 says a Mach-O cache "did not come from the CDN". #525 calls that origin "Not proven"; the claim is inferred from upstream's Linux-only CDN. The row also no longer says that such a build runs.

Context cost: 66271 → 66271 words (measured). doctor-triage.md is loaded on demand.

Time cost: nothing per build row.


Generated by Claude Code

@MendixMau
MendixMau merged commit f13609f into master Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants